<!doctype html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<link rel="stylesheet" href="./../../assets/css/combined.css">
	<link rel="shortcut icon" href="./../../favicon.ico" />
	<script src="http://www.google.com/jsapi" type="text/javascript"></script>
	<script type="text/javascript">
		var path = './../../';
		var class_prefix = "Validation::";
	</script>
	<script src="./../../assets/js/combined.js"></script>
	<title>Validation Methods - Classes - FuelPHP Documentation</title>
</head>
<body>
	<div id="container">
		<header id="header">
			<div class="table">
				<h1>
					<strong>FuelPHP, a PHP 5.3 Framework</strong>
					Documentation
				</h1>

				<form id="google_search">
					<p>
						<span id="search_clear">&nbsp;</span>
						<input type="submit" name="search_submit" id="search_submit" value="search" />
						<input type="text" value="" id="search_input" name="search_input" />
					</p>
				</form>
			</div>
			<nav>

				<div class="clear"></div>
			</nav>
			<a href="#" id="toc_handle">table of contents</a>
			<div class="clear"></div>
		</header>

		<div id="cse">
			<div id="cse_point"></div>
			<div id="cse_content"></div>
		</div>

		<div id="main">

			<h2>Validation Class</h2>

			<p>
				The Validation class helps you validate user input, if you want to create a form &amp; its validation at
				the same time use the <a href="../fieldset.html">Fieldset</a> class instead.
			</p>

			<h3 id="class_methods">Class Methods</h3>

			<article>
				<h4 class="method" id="method_forge">forge($fieldset = 'default')</h4>

				<p>
					The <strong>forge</strong> method returns a new Validation instance,
					and links it with a Fieldset with name $fieldset.
				</p>

				<table class="method">
					<tbody>
						<tr>
							<th class="legend">Static</th>
							<td>Yes</td>
						</tr>
						<tr>
							<th>Parameters</th>
							<td>
								<table class="parameters">
									<tr>
										<th>Param</th>
										<th>Type</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$fieldset</kbd></th>
										<td><em>string | Fieldset</em></td>
										<td><pre class="php"><code>'default'</code></pre></td>
										<td>The name or instance of the Fieldset to link to.</td>
									</tr>
							</table>
							</td>
						</tr>
						<tr>
							<th>Returns</th>
							<td>Validation object</td>
						</tr>
						<tr>
							<th>Throws</th>
							<td>\DomainException, when the Fieldset name or instance already has a related Validation instance.</td>
						</tr>
						<tr>
							<th>Example</th>
							<td>
								<pre class="php"><code>// Create a new validation instance
$val = Validation::forge();

// Associate the new Validation instance with a Fieldset, using the fieldset name
$val = Validation::forge('my_fieldset');

// Associate the new Validation instance with a Fieldset, by passing the fieldset instance
$fieldset = Fieldset::instance('my_fieldset');
$val = Validation::forge($fieldset);
</code></pre>
							</td>
						</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_instance">instance($name = null)</h4>

				<p>
					The <strong>instance</strong> method returns the Validation instance
					related with the Fieldset instance with the identifier $name,
					or the default Fieldset (is created if necessary).
				</p>

				<table class="method">
					<tbody>
						<tr>
							<th class="legend">Static</th>
							<td>Yes</td>
						</tr>
						<tr>
							<th>Parameters</th>
							<td>
								<table class="parameters">
									<tr>
										<th>Param</th>
										<th>Type</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$name</kbd></th>
										<td><em>string</em></td>
										<td><pre class="php"><code>null</code></pre></td>
										<td>The name of the Fieldset whose Validation instance you want to return.</td>
									</tr>
							</table>
							</td>
						</tr>
						<tr>
							<th>Returns</th>
							<td>
								Validation object<br />
								or <strong>false</strong> if the specified Fieldset instance doesn't exist
							</td>
						</tr>
						<tr>
							<th>Example</th>
							<td>
								<pre class="php"><code>// Get the Validation instance of the default Fieldset
$val = Validation::instance();

// Get the Validation instance of a particular Fieldset
$val = Validation::instance('my_fieldset');
</code></pre>
							</td>
						</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_active">active()</h4>
				<p>
					The <strong>active</strong> method returns the currently active validation instance.
				</p>
				<table class="method">
					<tbody>
						<tr>
							<th class="legend">Static</th>
							<td>Yes</td>
						</tr>
						<tr>
							<th>Parameters</th>
							<td>
								None
							</td>
						</tr>
						<tr>
							<th>Returns</th>
							<td>Validation - currently active validation instance</td>
						</tr>
						<tr>
							<th>Example</th>
							<td>
								<pre class="php"><code>// Get the currently active validation instance
$val = Validation::active();
</code></pre>
							</td>
						</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_active_field">active_field()</h4>
				<p>
					The <strong>active_field</strong> method returns the field currently being validated.
				</p>

				<table class="method">
					<tbody>
						<tr>
							<th class="legend">Static</th>
							<td>Yes</td>
						</tr>
						<tr>
							<th>Parameters</th>
							<td>
								None
							</td>
						</tr>
						<tr>
							<th>Returns</th>
							<td>Fieldset_Field - the field currently being validated</td>
						</tr>
						<tr>
							<th>Example</th>
							<td>
								<pre class="php"><code>// Get the field currently being validated
$field = Validation::active_field();
</code></pre>
							</td>
						</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_fieldset">fieldset()</h4>
				<p>
					The <strong>fieldset</strong> method returns the related Fieldset.
				</p>

				<table class="method">
					<tbody>
						<tr>
							<th class="legend">Static</th>
							<td>No</td>
						</tr>
						<tr>
							<th>Parameters</th>
							<td>
								None
							</td>
						</tr>
						<tr>
							<th>Returns</th>
							<td>Fieldset - the related Fieldset</td>
						</tr>
						<tr>
							<th>Example</th>
							<td>
								<pre class="php"><code>// Get the related Fieldset
$val = Validation::forge('my_fieldset');
$fieldset = $val->fieldset();
</code></pre>
							</td>
						</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_add_field">add_field($name, $label, $rules)</h4>
				<p>
					The <strong>add_field</strong> method is a simpler alias for add() method which allows specifying the field name, label and rules in a single step.
				</p>
				<table class="method">
					<tbody>
						<tr>
							<th class="legend">Static</th>
							<td>No</td>
						</tr>
						<tr>
							<th>Parameters</th>
							<td>
								<table class="parameters">
									<tr>
										<th>Param</th>
										<th>Type</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$name</kbd></th>
										<td><em>string</em></td>
										<td><pre class="php"><code>None</code></pre></td>
										<td>The field name to assign the validation rule to.</td>
									</tr>
									<tr>
										<th><kbd>$label</kbd></th>
										<td><em>string</em></td>
										<td><pre class="php"><code>None</code></pre></td>
										<td>Label of the field.</td>
									</tr>
									<tr>
										<th><kbd>$rules</kbd></th>
										<td><em>mixed</em></td>
										<td><pre class="php"><code>None</code></pre></td>
										<td>
											The set of validation rules with (optional) rule parameters grouped in square brackets,
											and separated with commas. It can be passed as a string where the rules are separated
											with a vertical bar or pipe symbol (|), or as a array of rules.
										</td>
									</tr>
								</table>
							</td>
						</tr>
						<tr>
							<th>Returns</th>
							<td>Fieldset_Field</td>
						</tr>
						<tr>
							<th>Example</th>
							<td>
								<pre class="php"><code>// Set rules on different types of fields
$val->add_field('username', 'Username', 'required|trim|valid_string[alpha,lowercase,numeric]');
$val->add_field('email', 'Email', 'required|trim|valid_email');
$val->add_field('age', 'Age', 'valid_string[numeric]');

// as an array
$val->add_field('username', 'Username', array('required', 'trim', 'valid_string[alpha,lowercase,numeric]'));</code></pre>
							</td>
						</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_set_message">set_message($rule, $message)</h4>
				<p>
					The <strong>set_message</strong> method overwrites the language file messages for this validation instance. It's also useful when no message is assigned to the rule you're using.
				</p>
				<table class="method">
					<tbody>
						<tr>
							<th class="legend">Static</th>
							<td>No</td>
						</tr>
						<tr>
							<th>Parameters</th>
							<td>
								<table class="parameters">
									<tr>
										<th>Param</th>
										<th>Type</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$rule</kbd></th>
										<td><em>string</em></td>
										<td><pre class="php"><code>None</code></pre></td>
										<td>Name of the rule to assign this message to.</td>
									</tr>
									<tr>
										<th><kbd>$message</kbd></th>
										<td><em>string | null</em></td>
										<td><pre class="php"><code>None</code></pre></td>
										<td>The message to display for this rule, if a string is passed, or null to revert to the language file.</td>
									</tr>
								</table>
							</td>
						</tr>
						<tr>
							<th>Returns</th>
							<td>Validation instance</td>
						</tr>
						<tr>
							<th>Example</th>
							<td>
								<pre class="php"><code>// Overwrite the required rule message
$val->set_message('required', 'You have to fill in your :label so you can proceed');
// .. when done, set back the default message
$val->set_message('required', null);
// A message for a custom rule you created
$val->set_message('custom_rule', 'The :label you entered is previously registered. Please choose another one');
</code></pre>
							</td>
						</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_get_message">get_message($rule)</h4>
				<p>
					The <strong>get_message</strong> method fetches a specific error message for this validation instance. Only messages set through the <a href="#method_set_message">set_message</a> method are returned.
				</p>
				<table class="method">
					<tbody>
						<tr>
							<th class="legend">Static</th>
							<td>No</td>
						</tr>
						<tr>
							<th>Parameters</th>
							<td>
								<table class="parameters">
									<tr>
										<th>Param</th>
										<th>Type</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$rule</kbd></th>
										<td><em>string</em></td>
										<td><pre class="php"><code>None</code></pre></td>
										<td>Name of the rule of which you need to get the message.</td>
									</tr>
								</table>
							</td>
						</tr>
						<tr>
							<th>Returns</th>
							<td>string</td>
						</tr>
						<tr>
							<th>Example</th>
							<td>
								<pre class="php"><code>// Overwrite the required rule message
$val->set_message('custom_rule', 'The :label you entered is previously registered. Please choose another one');
// .. later, or some where else in your code, get this message
$val->get_message('required', null);
</code></pre>
							</td>
						</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_add_callable">add_callable($class)</h4>
				<p>
					The <strong>add_callable</strong> method adds a set of custom or extended validation rules. You don't need to write a full callback, just the class name as a string will do. This also allows for overwriting functionality from this object because the new class is prepended.
				</p>
				<table class="method">
					<tbody>
						<tr>
							<th class="legend">Static</th>
							<td>No</td>
						</tr>
						<tr>
							<th>Parameters</th>
							<td>
								<table class="parameters">
									<tr>
										<th>Param</th>
										<th>Type</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$class</kbd></th>
										<td><em>string|Object</em></td>
										<td><pre class="php"><code>None</code></pre></td>
										<td>Name of the class as string, or object name</td>
									</tr>
								</table>
							</td>
						</tr>
						<tr>
							<th>Returns</th>
							<td>Validation instance</td>
						</tr>
						<tr>
							<th>Example</th>
							<td>
								<p><pre class="php"><code>$val->add_callable('myvalidation');</code></pre></p>
								<p>Check the <a href="validation.html#/extending_validation">Extending the Validation class</a> for a complete example of using this method, and the required class.</p>
							</td>
						</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_remove_callable">remove_callable($class)</h4>
				<p>
					The <strong>remove_callable</strong> method removes a callable from the callables array.
				</p>
				<table class="method">
					<tbody>
						<tr>
							<th class="legend">Static</th>
							<td>No</td>
						</tr>
						<tr>
							<th>Parameters</th>
							<td>
								<table class="parameters">
									<tr>
										<th>Param</th>
										<th>Type</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$class</kbd></th>
										<td><em>string|Object</em></td>
										<td><pre class="php"><code>None</code></pre></td>
										<td>Name of the class as string, or object name</td>
									</tr>
								</table>
							</td>
						</tr>
						<tr>
							<th>Returns</th>
							<td>Validation instance</td>
						</tr>
						<tr>
							<th>Example</th>
							<td>
								<pre class="php"><code>$val->remove_callable('myvalidation');</code></pre>
							</td>
						</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_callables">callables()</h4>
				<p>
					The <strong>callables</strong> method fetches the objects for which you don't need to add a full callback but just the method name
				</p>
				<table class="method">
					<tbody>
						<tr>
							<th class="legend">Static</th>
							<td>No</td>
						</tr>
						<tr>
							<th>Parameters</th>
							<td>None</td>
						</tr>
						<tr>
							<th>Returns</th>
							<td>array</td>
						</tr>
					</tbody>
				</table>
			</article>

			<p>More coming soon...</p>
		</div>

		<footer>
			<p>
				&copy; FuelPHP Development Team 2010-2013 - <a href="http://fuelphp.com">FuelPHP</a> is released under the MIT license.
			</p>
		</footer>
	</div>
</body>
</html>
